Remaining Routes

Part 2, Chapter 13


Next, let's finish setting up the routes:

Endpoint HTTP Method CRUD Method Result
/summaries GET READ get all summaries
/summaries/:id GET READ get a single summary
/summaries POST CREATE add a summary
/summaries/:id PUT UPDATE update a summary
/summaries/:id DELETE DELETE delete a summary

Again, for each, we'll:

  1. write a test
  2. run the test, to ensure it fails (red)
  3. write just enough code to get the test to pass (green)
  4. refactor (if necessary)

DELETE Route

Add the following tests to test_summaries.py in "project/tests":

def test_remove_summary(test_app_with_db):
    response = test_app_with_db.post(
        "/summaries/", data=json.dumps({"url": "https://foo.bar"})
    )
    summary_id = response.json()["id"]

    response = test_app_with_db.delete(f"/summaries/{summary_id}/")
    assert response.status_code == 200
    assert response.json() == {"id": summary_id, "url": "https://foo.bar"}


def test_remove_summary_incorrect_id(test_app_with_db):
    response = test_app_with_db.delete("/summaries/999/")
    assert response.status_code == 404
    assert response.json()["detail"] == "Summary not found"

Run the tests to ensure they both fail:

$ docker-compose exec web python -m pytest

You should the following errors:

>       assert response.status_code == 200
E       assert 405 == 200
E        +  where 405 = <Response [405]>.status_code

>       assert response.status_code == 404
E       assert 405 == 404
E        +  where 405 = <Response [405]>.status_code

Then add the route handler to project/app/api/summaries.py:

@router.delete("/{id}/", response_model=SummaryResponseSchema)
async def delete_summary(id: int) -> SummaryResponseSchema:
    summary = await crud.get(id)
    if not summary:
        raise HTTPException(status_code=404, detail="Summary not found")

    await crud.delete(id)

    return summary

Add the CRUD util to project/app/api/crud.py:

async def delete(id: int) -> int:
    summary = await TextSummary.filter(id=id).first().delete()
    return summary

Ensure the tests pass:

=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0, cov-3.0.0
collected 8 items

tests/test_ping.py .                                                        [ 12%]
tests/test_summaries.py .......                                             [100%]

================================ 8 passed in 0.26s ================================

PUT Route

Start with some tests:

def test_update_summary(test_app_with_db):
    response = test_app_with_db.post(
        "/summaries/", data=json.dumps({"url": "https://foo.bar"})
    )
    summary_id = response.json()["id"]

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({"url": "https://foo.bar", "summary": "updated!"})
    )
    assert response.status_code == 200

    response_dict = response.json()
    assert response_dict["id"] == summary_id
    assert response_dict["url"] == "https://foo.bar"
    assert response_dict["summary"] == "updated!"
    assert response_dict["created_at"]


def test_update_summary_incorrect_id(test_app_with_db):
    response = test_app_with_db.put(
        "/summaries/999/",
        data=json.dumps({"url": "https://foo.bar", "summary": "updated!"})
    )
    assert response.status_code == 404
    assert response.json()["detail"] == "Summary not found"


def test_update_summary_invalid_json(test_app_with_db):
    response = test_app_with_db.post(
        "/summaries/", data=json.dumps({"url": "https://foo.bar"})
    )
    summary_id = response.json()["id"]

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({})
    )
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["body", "url"],
                "msg": "field required",
                "type": "value_error.missing",
            },
            {
                "loc": ["body", "summary"],
                "msg": "field required",
                "type": "value_error.missing",
            }
        ]
    }

def test_update_summary_invalid_keys(test_app_with_db):
    response = test_app_with_db.post(
        "/summaries/", data=json.dumps({"url": "https://foo.bar"})
    )
    summary_id = response.json()["id"]

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({"url": "https://foo.bar"})
    )
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["body", "summary"],
                "msg": "field required",
                "type": "value_error.missing",
            }
        ]
    }

Ensure the tests fail.

Add the handler:

@router.put("/{id}/", response_model=SummarySchema)
async def update_summary(id: int, payload: SummaryUpdatePayloadSchema) -> SummarySchema:
    summary = await crud.put(id, payload)
    if not summary:
        raise HTTPException(status_code=404, detail="Summary not found")

    return summary

Add a new pydantic model to project/app/models/pydantic.py:

class SummaryUpdatePayloadSchema(SummaryPayloadSchema):
    summary: str

Make sure to import it in project/app/api/summaries.py:

from app.models.pydantic import (  # isort:skip
    SummaryPayloadSchema,
    SummaryResponseSchema,
    SummaryUpdatePayloadSchema,
)

Did you notice the isort:skip action comment? This prevents isort from formatting the associated import. It's necessary as both isort and Black will attempt to format it in different ways.

Util:

async def put(id: int, payload: SummaryPayloadSchema) -> Union[dict, None]:
    summary = await TextSummary.filter(id=id).update(url=payload.url, summary=payload.summary)
    if summary:
        updated_summary = await TextSummary.filter(id=id).first().values()
        return updated_summary
    return None

Do the tests pass now?

=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0, cov-3.0.0
collected 12 items

tests/test_ping.py .                                                        [  8%]
tests/test_summaries.py ...........                                         [100%]

=============================== 12 passed in 0.30s ================================

Additional Validation

Let's add some additional validation to the routes, checking that:

  1. The id is greater than 0 for reading, updating, and deleting a single summary
  2. The URL is valid for adding and updating a summary

GET

Update the test_read_summary_incorrect_id test:

def test_read_summary_incorrect_id(test_app_with_db):
    response = test_app_with_db.get("/summaries/999/")
    assert response.status_code == 404
    assert response.json()["detail"] == "Summary not found"

    response = test_app_with_db.get("/summaries/0/")
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["path", "id"],
                "msg": "ensure this value is greater than 0",
                "type": "value_error.number.not_gt",
                "ctx": {"limit_value": 0},
            }
        ]
    }

The test should fail:

>       assert response.status_code == 422
E       assert 404 == 422
E        +  where 404 = <Response [404]>.status_code

Update the handler:

@router.get("/{id}/", response_model=SummarySchema)
async def read_summary(id: int = Path(..., gt=0)) -> SummarySchema:
    summary = await crud.get(id)
    if not summary:
        raise HTTPException(status_code=404, detail="Summary not found")

    return summary

Make sure to import Path:

from fastapi import APIRouter, HTTPException, Path

So, we added the following metadata to the parameter with Path:

  1. ... - the value is required (Ellipsis)
  2. gt - the value must be greater than 0

The tests should pass. Try out the API documentation as well:

swagger ui error

POST

Update the test_create_summaries_invalid_json test:

def test_create_summaries_invalid_json(test_app):
    response = test_app.post("/summaries/", data=json.dumps({}))
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["body", "url"],
                "msg": "field required",
                "type": "value_error.missing",
            }
        ]
    }

    response = test_app.post("/summaries/", data=json.dumps({"url": "invalid://url"}))
    assert response.status_code == 422
    assert response.json()["detail"][0]["msg"] == "URL scheme not permitted"

The test should fail:

>       assert response.status_code == 422
E       assert 201 == 422
E        +  where 201 = <Response [201]>.status_code

To get the test to pass, update the SummaryPayloadSchema model like so:

class SummaryPayloadSchema(BaseModel):
    url: AnyHttpUrl

Here, we added additional validation to the pydantic model with the AnyHttpUrl validator.

Add the import:

from pydantic import BaseModel, AnyHttpUrl

PUT

Update the test_update_summary_incorrect_id test:

def test_update_summary_incorrect_id(test_app_with_db):
    response = test_app_with_db.put(
        "/summaries/999/",
        data=json.dumps({"url": "https://foo.bar", "summary": "updated!"})
    )
    assert response.status_code == 404
    assert response.json()["detail"] == "Summary not found"

    response = test_app_with_db.put(
        f"/summaries/0/",
        data=json.dumps({"url": "https://foo.bar", "summary": "updated!"})
    )
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["path", "id"],
                "msg": "ensure this value is greater than 0",
                "type": "value_error.number.not_gt",
                "ctx": {"limit_value": 0},
            }
        ]
    }

Update the handler:

@router.put("/{id}/", response_model=SummarySchema)
async def update_summary(payload: SummaryUpdatePayloadSchema, id: int = Path(..., gt=0)) -> SummarySchema:
    summary = await crud.put(id, payload)
    if not summary:
        raise HTTPException(status_code=404, detail="Summary not found")

    return summary

Update test_update_summary_invalid_keys as well:

def test_update_summary_invalid_keys(test_app_with_db):
    response = test_app_with_db.post(
        "/summaries/", data=json.dumps({"url": "https://foo.bar"})
    )
    summary_id = response.json()["id"]

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({"url": "https://foo.bar"})
    )
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["body", "summary"],
                "msg": "field required",
                "type": "value_error.missing",
            }
        ]
    }

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({"url": "invalid://url", "summary": "updated!"})
    )
    assert response.status_code == 422
    assert response.json()["detail"][0]["msg"] == "URL scheme not permitted"

This should pass.

DELETE

Test:

def test_remove_summary_incorrect_id(test_app_with_db):
    response = test_app_with_db.delete("/summaries/999/")
    assert response.status_code == 404
    assert response.json()["detail"] == "Summary not found"

    response = test_app_with_db.delete("/summaries/0/")
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["path", "id"],
                "msg": "ensure this value is greater than 0",
                "type": "value_error.number.not_gt",
                "ctx": {"limit_value": 0},
            }
        ]
    }

Make sure the tests fail.

Handler:

@router.delete("/{id}/", response_model=SummaryResponseSchema)
async def delete_summary(id: int = Path(..., gt=0)) -> SummaryResponseSchema:
    summary = await crud.get(id)
    if not summary:
        raise HTTPException(status_code=404, detail="Summary not found")

    await crud.delete(id)

    return summary

All tests should pass!

=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0, cov-3.0.0
collected 12 items

tests/test_ping.py .                                                        [  8%]
tests/test_summaries.py ...........                                         [100%]

=============================== 12 passed in 0.31s ================================

Parametrizing Test Functions

Parameterized tests allow a developer to run the same test multiple times with different data inputs.

Take note of these three tests:

def test_update_summary_incorrect_id(test_app_with_db):
    response = test_app_with_db.put(
        "/summaries/999/",
        data=json.dumps({"url": "https://foo.bar", "summary": "updated!"})
    )
    assert response.status_code == 404
    assert response.json()["detail"] == "Summary not found"

    response = test_app_with_db.put(
        f"/summaries/0/",
        data=json.dumps({"url": "https://foo.bar", "summary": "updated!"})
    )
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["path", "id"],
                "msg": "ensure this value is greater than 0",
                "type": "value_error.number.not_gt",
                "ctx": {"limit_value": 0},
            }
        ]
    }


def test_update_summary_invalid_json(test_app_with_db):
    response = test_app_with_db.post(
        "/summaries/", data=json.dumps({"url": "https://foo.bar"})
    )
    summary_id = response.json()["id"]

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({})
    )
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["body", "url"],
                "msg": "field required",
                "type": "value_error.missing",
            },
            {
                "loc": ["body", "summary"],
                "msg": "field required",
                "type": "value_error.missing",
            }
        ]
    }


def test_update_summary_invalid_keys(test_app_with_db):
    response = test_app_with_db.post(
        "/summaries/", data=json.dumps({"url": "https://foo.bar"})
    )
    summary_id = response.json()["id"]

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({"url": "https://foo.bar"})
    )
    assert response.status_code == 422
    assert response.json() == {
        "detail": [
            {
                "loc": ["body", "summary"],
                "msg": "field required",
                "type": "value_error.missing",
            }
        ]
    }

    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps({"url": "invalid://url", "summary": "updated!"})
    )
    assert response.status_code == 422
    assert response.json()["detail"][0]["msg"] == "URL scheme not permitted"

These tests really differ only in their inputs and expected outputs, so we can use the pytest.mark.parametrize decorator to enable parametrization of arguments in order to run the same test multiple times with different data configurations.

Replace the three tests with these two:

@pytest.mark.parametrize("summary_id, payload, status_code, detail", [
    [999, {"url": "https://foo.bar", "summary": "updated!"}, 404, "Summary not found"],
    [
        0,
        {"url": "https://foo.bar", "summary": "updated!"},
        422,
        [{"loc": ["path", "id"], "msg": "ensure this value is greater than 0", "type": "value_error.number.not_gt", "ctx": {"limit_value": 0}}]
    ],
    [
        1,
        {},
        422,
        [
            {"loc": ["body", "url"], "msg": "field required", "type": "value_error.missing"},
            {"loc": ["body", "summary"], "msg": "field required", "type": "value_error.missing"}
        ]
    ],
    [
        1,
        {"url": "https://foo.bar"},
        422,
        [{"loc": ["body", "summary"], "msg": "field required", "type": "value_error.missing"}]
    ],
])
def test_update_summary_invalid(test_app_with_db, summary_id, payload, status_code, detail):
    response = test_app_with_db.put(
        f"/summaries/{summary_id}/",
        data=json.dumps(payload)
    )
    assert response.status_code == status_code
    assert response.json()["detail"] == detail


def test_update_summary_invalid_url(test_app):
    response = test_app.put(
        "/summaries/1/",
        data=json.dumps({"url": "invalid://url", "summary": "updated!"})
    )
    assert response.status_code == 422
    assert response.json()["detail"][0]["msg"] == "URL scheme not permitted"

Add the import:

import pytest

Make sure the tests still pass.

Quality

How does our test coverage look?

$ docker-compose exec web python -m pytest --cov="."

=============================== test session starts ===============================
platform linux -- Python 3.10.1, pytest-6.2.5, py-1.11.0, pluggy-1.0.0
rootdir: /usr/src/app
plugins: anyio-3.4.0, cov-3.0.0
collected 14 items

tests/test_ping.py .                                                        [  7%]
tests/test_summaries.py .............                                       [100%]

---------- coverage: platform linux, python 3.10.1-final-0 -----------
Name                     Stmts   Miss Branch BrPart  Cover
----------------------------------------------------------
app/__init__.py              0      0      0      0   100%
app/api/__init__.py          0      0      0      0   100%
app/api/crud.py             24      0      4      0   100%
app/api/ping.py              6      0      0      0   100%
app/api/summaries.py        33      0      6      0   100%
app/config.py               13      2      2      0    87%
app/db.py                   17      7      2      1    58%
app/main.py                 18      3      0      0    83%
app/models/__init__.py       0      0      0      0   100%
app/models/pydantic.py       7      0      6      0   100%
app/models/tortoise.py       9      1      2      0    91%
----------------------------------------------------------
TOTAL                      127     13     22      1    91%


=============================== 14 passed in 0.68s ================================

Run Flake8, Black, and isort:

$ docker-compose exec web flake8 .
$ docker-compose exec web black .
$ docker-compose exec web isort .

Manual Testing

Commit and push your code up to GitHub to trigger a new build. Once the deploy is complete, test all the routes with HTTPie.

GET all summaries:

$ http GET https://sleepy-thicket-77414.herokuapp.com/summaries/

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 114
Content-Type: application/json
Date: Mon, 27 Dec 2021 21:38:05 GMT
Server: uvicorn
Via: 1.1 vegur

[
    {
        "created_at": "2021-12-27T15:32:57.872355+00:00",
        "id": 1,
        "summary": "dummy summary",
        "url": "https://testdriven.io"
    }
]

GET single summary:

$ http GET https://sleepy-thicket-77414.herokuapp.com/summaries/1/

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 112
Content-Type: application/json
Date: Mon, 27 Dec 2021 21:38:31 GMT
Server: uvicorn
Via: 1.1 vegur

{
    "created_at": "2021-12-27T15:32:57.872355+00:00",
    "id": 1,
    "summary": "dummy summary",
    "url": "https://testdriven.io"
}

POST:

$ http --json POST https://sleepy-thicket-77414.herokuapp.com/summaries/ url=https://testdriven.io

HTTP/1.1 201 Created
Connection: keep-alive
Content-Length: 38
Content-Type: application/json
Date: Mon, 27 Dec 2021 21:39:01 GMT
Server: uvicorn
Via: 1.1 vegur

{
    "id": 2,
    "url": "https://testdriven.io"
}

PUT:

$ http --json PUT https://sleepy-thicket-77414.herokuapp.com/summaries/2/ url=https://testdriven.io summary=super

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 104
Content-Type: application/json
Date: Mon, 27 Dec 2021 21:39:26 GMT
Server: uvicorn
Via: 1.1 vegur

{
    "created_at": "2021-12-27T21:39:01.699792+00:00",
    "id": 2,
    "summary": "super",
    "url": "https://testdriven.io"
}

DELETE:

$ http DELETE https://sleepy-thicket-77414.herokuapp.com/summaries/2/

HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 38
Content-Type: application/json
Date: Mon, 27 Dec 2021 21:39:47 GMT
Server: uvicorn
Via: 1.1 vegur

{
    "id": 2,
    "url": "https://testdriven.io"
}



✓ Mark as Completed